home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / mcmm.exe / Q_GUIDE.TXT < prev   
Text File  |  1992-10-02  |  19KB  |  530 lines
  1. Programmers Quick Guide to MCs Menu Maker v0.8
  2. ----------------------------------------------
  3.  
  4. Ok,so its not that quick a guide!,but there should be enough information here to
  5. allow use of the menus/windows without any further documentation.
  6. A list of all the functions that are necessary in order to create and maintain
  7. a menu and/or window structure are listed below.Example code to illustrate each
  8. call is also included,with a full working skeleton at the end of this
  9. documentation.Note:If a window is linked to a menu then on being displayed it
  10. will use its defaults however,if the window is displayed using window_show the
  11. gadget values are taken from the windows work area and therefore must be set
  12. first with win_set_item.Bascially if you *always* require the default values to
  13. be used then link the window to a menu otherwise you have to manage the window
  14. work area yourself (a demonstration of this in included at the end).
  15. Cursor keys allow up/down movement on the menus while tab allows input to
  16. circle around all a windows options.
  17.  
  18.  
  19. void menu_clear(int 1)
  20. ----------------------
  21.  
  22. Parameter 1 is a number representing the main background screen colour to be
  23. used.This function must be called first before any others as it contains code
  24. to initialize the menu/window system.
  25.  
  26. Example:
  27. --------
  28.  
  29. menu_clear(1);
  30.  
  31. Menu/window system will be initialized and main background colour will be 1,
  32. standard EGA/VGA 16 colour scheme is used (see documentation for list).
  33.  
  34.  
  35. void menu_declare(char *1)
  36. --------------------------
  37.  
  38. This call allows each possible selection on a menu to be declared.To link a
  39. particular option to a window the window number is contained in curly brackets
  40. before the option.Window and menu numbers are assigned depending on the order of
  41. declaration e.g. the first defined menu is menu 0 the second menu 1 etc, the
  42. same applies to windows.
  43.  
  44. Example:
  45. --------
  46.  
  47. menu_declare("A menu,{3}This option opens a window");
  48.  
  49. A menu will be defined,its number is dependant on if any other menus were
  50. created before it (as the above is an example of the first menu declaration its
  51. number will be 0).The first option in the menu will be the text "A menu" it has
  52. no direct link to a window,on selection it will set the global variables
  53. menu_option and menu_number,in this example both would equal 0 - for menu 0,
  54. option 0 selected.The second option would insert the text "This option opens a
  55. window",on selection window 3 would be openned and input would now be into this
  56. window.Note,no menus are actually displayed until a menu_display is issued.
  57.  
  58.  
  59. void window_declare(char *1,int 2,int 3,int 4,int 5,char *6)
  60. ------------------------------------------------------------
  61.  
  62. Allows a window to be defined.The order of declaration will define the window
  63. number.All window declarations must end in a curly bracketed 0.Parameter 1
  64. allows for an automatically centered window title to be displayed,if this is
  65. left as a null ("") then no title will be displayed.Parameters 2 and 3 are the
  66. windows size in characters (x,y).Parameters 4 and 5 determine the x,y coordinate
  67. to place the window at,if both are 0 then the window is placed below and
  68. slightly to the right (where ever possible) of the menu option that selected it.
  69. If either value is not 0 then the window is placed directly at these coordinates
  70. (origin top left 0,0).The final parameter 6 contains the window gadget types
  71. required,currently supported types are listed below.Note all x,y coordinates
  72. are relative to the windows origin.
  73.  
  74.         type 1 text (x,y,col,string)
  75.         Parameters x,y are the coordinates to place the text at.Col is the
  76.         colour to use to display text and finally string is the actual text
  77.         itself.
  78.  
  79.         Example:
  80.         --------
  81.  
  82.         "{1}{10}{9}{15}Some text"
  83.  
  84.         The text "Some text" will be displayed at coordinates 10,9 in colour
  85.         15.
  86.  
  87.  
  88.         type 2 switcher (x,y,num,def)
  89.         Parameters x,y are the coordinates to place the first switch at.Num is
  90.         the total number of switches displayed.Finally def is the number of the
  91.         default switch to be highlighted.
  92.  
  93.         Example:
  94.         --------
  95.  
  96.         "{2}{3}{4}{4}{2}"
  97.  
  98.         4 switches will be displayed starting at coordinates 3,4,switch 2 is
  99.         the default hence highlighted one.
  100.  
  101.  
  102.         type 3 number (x,y,min,max,def)
  103.         Parameters x,y are the coordinates to place the input box.Min and Max
  104.         define the minimum and maximum value to accept.Def is the default
  105.         value.
  106.  
  107.         Example:
  108.         --------
  109.  
  110.         "{3}{10}{11}{5}{10}{6}"
  111.  
  112.         An input box will displayed at coordinates 10,11,it will accept only
  113.         values between 5 and 10 inclusive.The default value is 6.
  114.  
  115.  
  116.         type 4 boolean (x,y,def)
  117.         Parameters x,y are the coordinates to place the alternator at.Def is
  118.         the default selection (1=Yes,0=No).
  119.  
  120.         Example:
  121.         --------
  122.  
  123.         "{4}{7}{4}{1}"
  124.  
  125.         A boolean alternator will be displayed at coordinates 7,4.Its default
  126.         will be YES.
  127.  
  128.  
  129.         type 5 file (x,y,height,type)
  130.         Parameters x,y are the coordinates to place the start of the file box
  131.         at.Height is the height of the box in characters.Type defines what
  132.         action to take on a selection,(0=exit on selection of file to calling
  133.         program,1=don't,this allows for just directory selection).The current
  134.         directory will be used.
  135.  
  136.         Example:
  137.         --------
  138.  
  139.         "{5}{6}{7}{10}{0}"
  140.  
  141.         A file selection box will be displayed at coordinates 6,7.Its height
  142.         will be 10 characters.On a file selection control will return to the
  143.         calling enviroment.
  144.  
  145.  
  146.         type 6 char (x,y,len,type,def)
  147.         Parameters x,y are the coordinates to place the start of the input box
  148.         at.Len is the maximum length of input string to accept.Type defines
  149.         what action to take on <return> being pressed,(0=normal, string is
  150.         stored but no action taken,1=exit on entry to calling program).Def is
  151.         the default string to be displayed.
  152.  
  153.         Example:
  154.         --------
  155.  
  156.         "{6}{17}{8}{10}{0}"
  157.  
  158.         An input box will be displayed at coordinates 17,8.Maximum input length
  159.         of string will be 10 characters.On <return> no action will result,apart
  160.         from storage of the string.
  161.  
  162.  
  163.         type 7 accept (x,y,text)
  164.         Parameters x,y are the coordinates to place the icon at.Text is the
  165.         actual icon text to display.
  166.  
  167.         Example:
  168.         --------
  169.  
  170.         "{7}{6}{22}OK"
  171.  
  172.         An icon will be displayed at coordinates 6,22.Its text will be "OK".
  173.  
  174.  
  175. Full Example:
  176. -------------
  177.  
  178. window_declare("A window",50,20,0,0,"{1}{2}{2}{9}Hi,{3}{2}{5}{2}{10}{5},{0}");
  179.  
  180. A window with title "A window" of size 50,20 will be declared.When displayed
  181. it will appear one character down and one character to the right of the menu
  182. option that selected it if possible.The text string "Hi" will be displayed in
  183. colour 9 at coordinates 2,2.A number input box will be displayed at coordinates
  184. 2,5 it will accept a value between 2 and 10 inclusive,with the default displayed
  185. value being 5.Note the {0} terminator.
  186.  
  187.  
  188. int window_show(int 1,int 2,int 3)
  189. ----------------------------------
  190.  
  191. Window with the number parameter 1 will be displayed at coordinates parameter
  192. 2,parameter 3.This allows windows to be used without a menu selection being
  193. made or without any menus at all.The returned value is either the ASCII code
  194. of a 'non-window' key or a status value (see documentation).Note:default gadget
  195. values are overwrote as any values are read from the gadgets work space.
  196.  
  197. Example:
  198. --------
  199.  
  200. key=window_show(5,10,10);
  201.  
  202. Display window 5 at coordinates 10,10.
  203.  
  204.  
  205. void window_help_declare(int 1,int 2,char *3)
  206. ---------------------------------------------
  207.  
  208. A window option must have a help string attached to it (null for none).
  209. Parameter 1 defines which window the help is attached to.Parameter 2 defines
  210. which gadget within that window the help is attached to.Parame